# Exceptions

This document was not updated for the J2SETM release. If you downloaded this document as part of the J2SETM documentation bundle, check the Web site at http://java.sun.com/j2se/1.4/docs/guide/idl/jidlExceptions.html for updates. This document is included in the bundle because the information contained in this document is relevant to this release, although it is not specifically written for this release.

CORBA has two types of exceptions: standard system exceptions which are fully specified by the OMG and user exceptions which are defined by the individual application programmer. CORBA exceptions are a little different from Java exception objects, but those differences are largely handled in the mapping from IDL to Java.

Topics in this section include:

- Differences Between CORBA and Java Exceptions
- System Exceptions
  - System Exception Structure
  - Minor Codes
  - Completion Status
- User Exceptions
- Minor Code Meanings

## Differences Between CORBA and Java Exceptions

To specify an exception in IDL, the interface designer uses the raises keyword. This is similar to the throws specification in Java. When you use the exception keyword in IDL you create a user-defined exception. The standard system exceptions need not (and cannot) be specified this way.

## System Exceptions

CORBA defines a set of standard system exceptions, which are generally raised by the ORB libraries to signal systemic error conditions like:

- Server-side system exceptions, such as resource exhaustion or activation failure.
- Communication system exceptions, for example, losing contact with the object, host down, or cannot talk to ORB daemon (orbd).
- Client-side system exceptions, such as invalid operand type or anything that occurs before a request is sent or after the result comes back.

All IDL operations can throw system exceptions when invoked. The interface designer need not specify anything to enable operations in the interface to throw system exceptions -- the capability is automatic.

This makes sense because no matter how trivial an operation's implementation is, the potential of an operation invocation coming from a client that is in another process, and perhaps (likely) on another machine, means that a whole range of errors is possible.

Therefore, a CORBA client should always catch CORBA system exceptions. Moreover, developers cannot rely on the Java compiler to notify them of a system exception they should catch, because CORBA system exceptions are descendants of `java.lang.RuntimeException`.

### System Exception Structure

All CORBA system exceptions have the same structure:

    exception <SystemExceptionName> { // descriptive of error
        unsigned long minor;          // more detail about error
        CompletionStatus completed;   // yes, no, maybe
    }

System exceptions are subtypes of `java.lang.RuntimeException` through `org.omg.CORBA.SystemException`:

    java.lang.Exception
     |
     +--java.lang.RuntimeException
         |
         +--org.omg.CORBA.SystemException
             |
             +--BAD_PARAM
             |
             +--//etc.

### Minor Codes

All CORBA system exceptions have a minor code field, a number that provides additional information about the nature of the failure that caused the exception. Minor code meanings are not specified by the OMG; each ORB vendor specifies appropriate minor codes for that implementation. For the meaning of minor codes thrown by the Java ORB, see Minor code meanings .

### Completion Status

All CORBA system exceptions have a completion status field, indicating the status of the operation that threw the exception. The completion codes are:

COMPLETED_YES
  The object implementation has completed processing prior to the exception being raised.
COMPLETED_NO
  The object implementation was not invoked prior to the exception being raised.
COMPLETED_MAYBE
  The status of the invocation is unknown.

## User Exceptions

CORBA user exceptions are subtypes of `java.lang.Exception` through `org.omg.CORBA.UserException`:

    java.lang.Exception
     |
     +--org.omg.CORBA.UserException
          |
          +-- Stocks.BadSymbol
          |
          +--//etc.

Each user-defined exception specified in IDL results in a generated Java exception class. These exceptions are entirely defined and implemented by the programmer

## Minor Code Meanings

System exceptions all have a field minor that allows CORBA vendors to provide additional information about the cause of the exception. The table below lists the minor codes of Java IDL's system exceptions, along with their significance.

ORB Minor Codes and Their Meanings
Code | Meaning
--- | ---
BAD_PARAM Exception Minor Codes
1 | A null parameter was passed to a Java IDL method.
COMM_FAILURE Exception Minor Codes
1 | Unable to connect to the host and port specified in the object reference, or in the object reference obtained after location/object forward.
2 | Error occurred while trying to write to the socket. The socket has been closed by the other side, or is aborted.
3 | Error occurred while trying to write to the socket. The connection is no longer alive.
6 | Unable to successfully connect to the server after several attempts.
DATA_CONVERSION Exception Minor Codes
1 | Encountered a bad hexadecimal character while doing ORB `string_to_object` operation.
2 | The length of the given IOR for `string_to_object()` is odd. It must be even.
3 | The string given to `string_to_object()` does not start with `IOR:` and hence is a bad stringified IOR.
4 | Unable to perform ORB `resolve_initial_references` operation due to the host or the port being incorrect or unspecified, or the remote host does not support the Java IDL bootstrap protocol.
INTERNAL Exception Minor Codes
3 | Bad status returned in the IIOP Reply message by the server.
6 | When unmarshaling, the repository id of the user exception was found to be of incorrect length.
7 | Unable to determine local hostname using the Java APIs `InetAddress.getLocalHost().getHostName()`.
8 | Unable to create the listener thread on the specific port. Either the port is already in use, there was an error creating the daemon thread, or security restrictions prevent listening.
9 | Bad locate reply status found in the IIOP locate reply.
10 | Error encountered while stringifying an object reference.
11 | IIOP message with bad GIOP v1.0 message type found.
14 | Error encountered while unmarshaling the user exception.
18 | Internal initialization error.
INV_OBJREF Exception Minor Codes
1 | An IOR with no profile was encountered.
MARSHAL Exception Minor Codes
4 | Error occured while unmarshaling an object reference.
5 | Marshalling/unmarshaling unsupported IDL types like wide characters and wide strings.
6 | Character encountered while marshaling or unmarshaling a character or string that is not ISO Latin-1 (8859.1) compliant. It is not in the range of 0 to 255.
NO_IMPLEMENT Exception Minor Codes
1 | Dynamic Skeleton Interface is not implemented.
OBJ_ADAPTER Exception Minor Codes
1 | No object adapter was found matching the one in the object key when dispatching the request on the server side to the object adapter layer.
2 | No object adapter was found matching the one in the object key when dispatching the locate request on the server side to the object adapter layer.
4 | Error occured when trying to connect a servant to the ORB.
OBJ_NOT_EXIST Exception Minor Codes
1 | Locate request got a response indicating that the object is not known to the locator.
2 | Server id of the server that received the request does not match the server id baked into the object key of the object reference that was invoked upon.
4 | No skeleton was found on the server side that matches the contents of the object key inside the object reference.
UNKNOWN Exception Minor Codes
1 | Unknown user exception encountered while unmarshaling: the server returned a user exception that does not match any expected by the client.
3 | Unknown runtime exception thrown by the server implementation.

Name Server Minor Codes and Their Meanings
Code | Meaning
--- | ---
INITIALIZE Exception Minor Codes
150 | Transient name service caught a `SystemException` while initializing.
151 | Transient name service caught a Java exception while initializing.
INTERNAL Exception Minor Codes
100 | An `AlreadyBound` exception was thrown in a `rebind` operation.
101 | An `AlreadyBound` exception was thrown in a `rebind_context` operation.
102 | Binding type passed to the internal binding implementation was not `BindingType.nobject` or `BindingType.ncontext`.
103 | Object reference was bound as a context, but it could not be narrowed to `CosNaming.NamingContext`.
200 | Implementation of the `bind` operation encountered a previous binding.
201 | Implementation of the `list` operation caught a Java exception while creating the list iterator.
202 | Implementation of the `new_context` operation caught a Java exception while creating the new `NamingContext` servant.
203 | Implementaton of the `destroy` operation caught a Java exception while disconnecting from the ORB.

Home

Copyright © 1996-98 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.